Overview

This is the next ICMP Echo follow-up after #13189 and #13281.

It adds an icmp.Forwarder adapter for ICMP packets delivered through stack.SetTransportProtocolHandler, and lets the handler explicitly delegate ICMP Echo Reply generation back to netstack with ForwarderRequest.Reply().

The goal is to let embedders handle ICMP Echo Requests without reimplementing the built-in reply construction logic downstream.

Behavior

The default behavior remains conservative:

no ICMP default handler                   -> built-in Echo Reply is preserved
default handler returns false, no Reply() -> built-in Echo Reply is preserved
default handler returns true, no Reply()  -> no built-in Echo Reply
registered ICMP endpoint                  -> default handler is not called; built-in Echo Reply is preserved
IPv4 LocalAddressTemporary                -> built-in Echo Reply is still suppressed unless the handler explicitly calls Reply()

The new explicit delegation path is:

f := icmp.NewForwarder(func(r *icmp.ForwarderRequest) bool {
    if shouldHandleByTunnel(r) {
        return handleByTunnel(r)
    }
    return r.Reply()
})

s.SetTransportProtocolHandler(icmp.ProtocolNumber4, f.HandlePacket)
s.SetTransportProtocolHandler(icmp.ProtocolNumber6, f.HandlePacket)

Reply() is idempotent. If a handler calls Reply() and then returns false, netstack does not synthesize a second built-in Echo Reply on the fallback path. A successful Reply() return means the built-in reply path was available and accepted for this request; it is not a packet-delivery guarantee.

API Semantics

This API keeps the existing SetTransportProtocolHandler ownership contract:

handler returns true   -> the handler consumed the packet
handler returns false  -> the handler did not consume the packet; protocol fallback may continue

ForwarderRequest.Reply() is a separate explicit action. It asks netstack to synthesize the built-in Echo Reply for this request, without changing what the handler's return value means.

That gives handlers two independent decisions:

return true without Reply()   -> consume/drop/forward the Echo Request; no built-in reply
return false without Reply()  -> do not consume it; preserve the current fallback behavior
Reply(); return true          -> explicitly send the built-in reply and consume the request
Reply(); return false         -> explicitly send the built-in reply, then allow fallback to continue without sending a duplicate reply

I kept the final API as bool + Reply() because it fits the existing default-handler contract and keeps the user-facing surface small. An action enum could model this, but it would need to combine two distinct decisions: whether the handler consumed the packet, and whether it asked netstack to send the built-in Echo Reply. Keeping Reply() as an explicit request method avoids redefining SetTransportProtocolHandler semantics for ICMP.

LocalAddressTemporary

This change keeps the no-handler IPv4 LocalAddressTemporary behavior from #11609 and #13189: temporary local addresses do not automatically trigger a built-in Echo Reply.

The new capability is explicit delegation. If the ICMP default handler sees r.PacketInfo().LocalAddressTemporary and decides that netstack should still generate the Echo Reply, it can call r.Reply(). In that path, the reply uses the original Echo Request destination address as the reply source, and the reply path can find a route without requiring that temporary address to be registered as the route local address.

That addresses the large-address-space embedder case discussed in #13189 without changing the conservative default for tunnel/proxy handlers that intentionally consume Echo Requests.

This does not add an IPv6 Temporary()-based Echo Reply suppression rule.

Implementation Notes

The user-facing adapter is intentionally small:

• icmp.NewForwarder(handler) constructs a handler adapter.
• Forwarder.HandlePacket can be passed to stack.SetTransportProtocolHandler.
• ForwarderRequest.ID() exposes the parsed ICMP identifier through stack.TransportEndpointID.
• ForwarderRequest.PacketBuffer() exposes the packet for the duration of the handler call.
• ForwarderRequest.PacketInfo() exposes network-layer metadata such as LocalAddressTemporary.
• ForwarderRequest.Reply() delegates to the built-in Echo Reply path.

The actual Echo Reply construction remains in the IPv4/IPv6 network endpoint layer. transport/icmp does not duplicate route lookup, source address selection, rate limiting, stats, checksum handling, IPv4 options, IPv6 traffic class, or output hooks.

The per-packet reply hook is not the intended embedder-facing API. Embedders should use ForwarderRequest.Reply(); the exported PacketBuffer hook helpers are a cross-package bridge that lets the network endpoint path expose its built-in reply operation to the ICMP forwarder without moving protocol-specific reply construction into transport/icmp.

The hook is deliberately scoped to packet delivery:

• PacketBuffer stores a private transient hook object.
• NetworkPacketInfo remains metadata-only.
• ForwarderRequest is invalidated after the handler returns.
• PacketBuffer.Clone() does not copy the reply hook.
• The IPv4/IPv6 ICMP paths clear the hook after transport delivery.

This keeps the hook from escaping past the temporary reply buffers prepared by the network endpoint.

Tests

The added tests cover:

• IPv4 and IPv6 Reply() delegation.
• Reply() idempotence when a handler returns false after replying.
• Forwarder consuming an Echo Request without Reply().
• Reply() returning false for non-Echo-Request packets.
• saved request / saved PacketBuffer invalidation after handler return.
• cloned PacketBuffer not inheriting the reply hook.
• IPv4 temporary-address default suppression and explicit Reply() override.

go run github.com/bazelbuild/bazelisk@latest test --nocache_test_results \
  //pkg/tcpip/network/ipv4:ipv4_test \
  //pkg/tcpip/network/ipv6:ipv6_test \
  //pkg/tcpip/network/ipv6:ipv6_x_test \
  //pkg/tcpip/transport/icmp:icmp_x_test \
  //pkg/tcpip/transport/icmp:icmp_nogo \
  //pkg/tcpip/stack:stack_test \
  //pkg/tcpip/stack:stack_x_test \
  //pkg/tcpip/stack:stack_nogo

Related

• netstack: let ICMP echo handlers consume requests #13189
• netstack: factor ICMP echo reply helpers #13281